Creating or Updating Accounts

An account is a unique identifier (UUID) that is used to associate a set of credentials and transactions (i.e. workflow executions) with a customer. Each transaction is associated with one account, and an account can be associated with multiple transactions.

  • If you are onboarding a new customer, use the POST request to create a new account.

  • If you are updating an existing account, use the PUT request, with the account ID value as a path parameter.

For the complete API specification see: Account API Reference.

Creating or updating the account is always done through a REST API call, regardless of the integration channel. Account requests are subject to Rate Limits.

Account Request

The request body for either an account creation or account update request is a JSON object.

Required Fields

Field Type Max. Length Notes
customerInternalReference string 100 Customer internal reference for a request to link it in the customer backend (must not contain any PII). Must not contain any of the following characters: <>"/;`%{}|
workflowDefinition object string 255 A key value is required to specify the workflow for the transaction. Other values may be required, depending on the workflow.

Account Request Body Required Fields Example

{
   "customerInternalReference":"myOrganization",
   "workflowDefinition":{
      "key": 10011
   }
}

Optional Fields

Field Type Max. Length Notes
userReference string 100 Reference for the end user in the customer backend (must not contain any PII)
reportingCriteria string 255 Additional information provided by a customer for searching and aggregation purposes
callbackUrl string 255 Definition of the callback URL for this particular request. Overrides callback URL in the Customer Portal.
tokenLifetime string min: 5m, max: 60d,
default: 30m
Should be a valid date period unit definition: s - seconds, m - minutes, h - hours d - days. Example: ‘1d’ / ‘30m’ / ‘600s’. Overrides Authorization token lifetime in the Customer Portal.
web object   Used to override default values that are configured in the Portal. Only relevant for the WEB channel.
userConsent object   If your integration uses REST APIs for Credential Acquisition you must obtain the end-user's consent to share their personal information with Jumio. See: End-User Consent to Collect Personal Data.
overrideSettings

object

 

Used to override some tenant settings.

workflowDefinition

A workflowDefinition object is required for all requests, and must include a key value that specifies the workflow for the transactionClosed An executed business process that is associated with an account. The transaction applies credentials for the account to a workflow and contains the decision rendered by the workflow..

Additional objects may be required to configure workflows that use some servicesClosed An identity verification service provided by Jumio that evaluates a set of credentials and renders a decision. A service is invoked by a workflow. A workflow can invoke a single service or a sequence of services and/or risk signals. or risk signalsClosed Risk signals are additional third-party services that can be invoked by a workflow. They are typically used to augment the standard services and provide extra assurance for determining the end user’s fraud risk., including:

  • credentials object used to specify a particular type of credential to upload for the transaction. For example, the Document Verification service (standalone workflow 10026, or any workflow that uses the Extraction capability to extract data from a Document credential

  • capabilities object used to specify configuration options for specific capabilities.

credentials

An array of the credentials required for the workflow. A credentials array is required if credentials are going to be uploaded by REST API calls. A credentials array is also used to:

  • Limit the sets of ID types and countries that are presented to end user during the customer journey. For example, the following limits the end user to choosing either USA or Canada, and either Driving License or ID Card. No other options are presented.

    "credentials": [
             {
                "category": "ID",
                "country": {
                   "predefinedType": "DEFINED",
                   "values": ["USA", "CAN"]
                },
                "type": {
                   "predefinedType": "DEFINED",
                   "values": ["DRIVING_LICENSE", "ID_CARD"]
                }  
             }
          ]
    Due to a limitation in the Web Client, only the first specified country and type value will be shown to the end user.
  • Specify a Document credential to use with a Document Verification workflow such as 10026. In this case the type and country must be specified to enable the Extraction capability. For example, the following is required to enable the extraction of expected values from a Bank Statement from the USA:

          "credentials": [
                {
                    "category": "DOCUMENT",
                    "country": {
                        "predefinedType": "DEFINED",
                        "values": ["USA"]
                    },
                    "type": {
                        "predefinedType": "DEFINED",
                        "values": ["BS"]
                    }  
                }
            ]
Field Type Notes
id string UUID of the credentials
category string Credential category. Possible values:
  • ID

  • DOCUMENT

  • FACEMAP

    It is not common to specify a FACEMAP. Consult with your account representative for additional information.
country object Defined at least one ISO 3166-1 alpha-3 country code for the workflow definition. Possible values: ISO 3166-1 alpha-3 country code
type object Defined number of credential type codes. Possible values:
  • ID_CARD
  • DRIVING LICENSE
  • PASSPORT
  • VISA

capabilities

Provide values for capabilities that require additional configuration properties.

Field Type Notes
watchlistScreening object Override the default search profile.
documentVerification object Configure additional capabilities to use with Document Verification.

ekycCheck

object

Used to specify a 1+1 or 2+2 search.

workflowDecision

object

Used to specify a ruleset to use instead of the default ruleset configured for the tenant.

ruleset object Override the default ruleset used by the workflow.
watchlistScreening

Used to configure the Watchlist Screening capability by overriding the default searchProfile. Consult your Jumio representative for additional information.

        "capabilities":{
           "watchlistScreening": {
           }
        }
searchProfile is the alphanumeric string that is the identifier for your searchProfile.
documentVerification

Used to disable Extraction in cases where a Document is uploaded to be stored but extracting the data is not required. Consult your Jumio representative for additional information.

        "capabilities": {
            "documentVerification": {
                "enableExtraction": "false"
            }
        }
ekycCheck

Includes a searchType value. Allowed values are:

  • one if requesting a 1+1 check

  • two if requesting a 2+x2 check

        "capabilities": {
          "ekycCheck": {
            "searchType": "one"
          }
        }
workflowDecision

Used to specify a ruleset to use instead of the default ruleset configured for the tenant.

        "capabilities": {
          "workflowDecision": {
            "riskScoreRulesetId": "81c616b7-d47e-4cb2-8c4f-17267f2106f3"
          } 
        }
ruleset
Using a workflowDecision objectis preferred to using ruleset for most cases.

Used to specify one or more rulesets to use instead of the default ruleset(s) used by the workflow.

        "capabilities": {
            "ruleset": {
                "ids": ["id1", "id2", "id3"]
            }
        }

The values in the "ids" array are the ruleset IDs of the rulesets you want to use. See also: Working with Rules.

web

These values are only relevant for the WEB channel. They are used to override the default values that are configured in the Portal. See Application Settings

Field Type Max. Length Notes
successUrl string 1900 URL to which the browser will send the end user at the end of a successful web acquisition user journey. Overrides default success URL.*
errorUrl string 1900 URL to which the browser will send the end user at the end of a failed web acquisition user journey. Overrides default error URL.*
locale string 5 Renders content in the specified language. Overrides Default locale.
* Success and error URLs provided through an Account request are less restrictive than the defaults. For example, local domains and schemes for deep linking are supported.

web Object Example

"web":{
    "successUrl":"https://www.yourcompany.com/success",
    "errorUrl":"https://www.yourcompany.com/error",
    "locale":"es"
}

userConsent

See End-User Consent to Collect Personal Data for details.

User Consent JSON

"userConsent": {
    "userIp": "226.80.211.232",
    "userLocation": {
      "country": "USA",
      "state": "IL"
    },
    "consent": {
      "obtained": "yes",
      "obtainedAt": "2022-07-20T17:20:35.000Z"
    }
  }

overrideSettings

You can override some tenant settings for a transaction.

Field Type Notes
crossDeviceOnly boolean Specifies whether or not the credential acquisition must be done on a mobile device.
crossDeviceOption string Specifies how a mobile device can get the connection. Options are:
  • DEFAULT (end user can choose email or QR Code)

  • QR_ONLY (Only the QR Code option will be shown)

  • EMAIL_ONLY (Only the email option will be shown)

overrideSettings Object Example

{
    "customerInternalReference":"myCompany",
    "overrideSettings":{
        "crossDeviceOnly": true,
        "crossDeviceOption":"QR_ONLY"
    },
    "workflowDefinition":{
        ...
    }
}

Account Responses

The response from the API includes the UUID and additional information you will need for the transaction, including:

  • The account ID and the workflow execution ID for the transaction. These values are used for Viewing or Retrieving Workflow Transactions.
  • The fully parameterized URL for the Web Client
  • The authorization token you will need if you are using one of the Mobile SDKs.
  • Details about the credentials that need to be provided for evaluation by the workflow. This includes data that will be used by the integration channel to upload the credential and associate it with the account.
    Workflows that evaluate multiple instances of the same type of credential can provide a "label" value to distinguish between the instances.
  • The URLs you will use if you are Uploading Credentials using the REST APIs for Credential Acquisition.

Example Account Response

{
    "timestamp": "2022-11-28T23:45:02.536Z",
    "account": {
        "id": "572ac7b5-9f83-409d-ba8e-f0014e411c7e"
    },
    "web": {
        "href": "https://greenunion.web.amer-1.jumio.ai/web/v4/app?authorizationToken=eyJhbGciOiJIUzUxMiIsInppcCI6IkdaSVAifQ.H4sIAAAAAAAA_5XOMQ7CMAwF0LtkxpKdOk7MxsjKDRInYWkBiUogIe5O2huw_v_09T-uvU-rOzoSUYka0XNSd3DZ7FxHHqLPFksA7WkCRq1QcmrQEYkbE1lsG98xU4-k5IFMCnDzHcrECFWqEVoVLWngV2__cLu0PvTj_lyXfIP1vlzB8jz7rduHvHRGDAmIMQB7GSeFK0zGOan2ZiG57w9fvJLI7AAAAA.0NpDK192_6kMSYfxFuqHPFkhdsKQBqieRvSqt3XAGLWRe7Y8u0aJalMa8TLEY8eA0XEw4TqRapVLDraRHUz4kQ&locale=en-US"
    },
    "sdk": {
        "token": "eyJhbGciOiJIUzUxMiIsInppcCI6IkdaSVAifQ.H4sIAAAAAAAA_5XOMQ7CMAwF0LtkxpKdOk7MxsjKDRInYWkBiUogIe5O2huw_v_09T-uvU-rOzoSUYka0XNSd3DZ7FxHHqLPFksA7WkCRq1QcmrQEYkbE1lsG98xU4-k5IFMCnDzHcrECFWqEVoVLWngV2__cLu0PvTj_lyXfIP1vlzB8jz7rduHvHRGDAmIMQB7GSeFK0zGOan2ZiG57w9fvJLI7AAAAA.0NpDK192_6kMSYfxFuqHPFkhdsKQBqieRvSqt3XAGLWRe7Y8u0aJalMa8TLEY8eA0XEw4TqRapVLDraRHUz4kQ"
    },
    "workflowExecution": {
        "id": "41f71912-1c6b-4e2f-b340-d6dc10cd69b8",
        "credentials": [
            {
                "id": "fdb1bc31-99a0-4671-8f2a-2bf7ca2faace",
                "category": "ID",
                "allowedChannels": [
                    "WEB",
                    "API",
                    "SDK"
                ],
                "api": {
                    "token": "eyJhbGciOiJIUzUxMiIsInppcCI6IkdaSVAifQ.H4sIAAAAAAAA_5XOMQ7CMAwF0LtkxpKdOk7MxsjKDRInYWkBiUogIe5O2huw_v_09T-uvU-rOzoSUYka0XNSd3DZ7FxHHqLPFksA7WkCRq1QcmrQEYkbE1lsG98xU4-k5IFMCnDzHcrECFWqEVoVLWngV2__cLu0PvTj_lyXfIP1vlzB8jz7rduHvHRGDAmIMQB7GSeFK0zGOan2ZiG57w9fvJLI7AAAAA.0NpDK192_6kMSYfxFuqHPFkhdsKQBqieRvSqt3XAGLWRe7Y8u0aJalMa8TLEY8eA0XEw4TqRapVLDraRHUz4kQ",
                    "parts": {
                        "front": "https://api.amer-1.jumio.ai/api/v1/accounts/572ac7b5-9f83-409d-ba8e-f0014e411c7e/workflow-executions/41f71912-1c6b-4e2f-b340-d6dc10cd69b8/credentials/fdb1bc31-99a0-4671-8f2a-2bf7ca2faace/parts/FRONT",
                        "back": "https://api.amer-1.jumio.ai/api/v1/accounts/572ac7b5-9f83-409d-ba8e-f0014e411c7e/workflow-executions/41f71912-1c6b-4e2f-b340-d6dc10cd69b8/credentials/fdb1bc31-99a0-4671-8f2a-2bf7ca2faace/parts/BACK"
                    },
                    "workflowExecution": "https://api.amer-1.jumio.ai/api/v1/accounts/572ac7b5-9f83-409d-ba8e-f0014e411c7e/workflow-executions/41f71912-1c6b-4e2f-b340-d6dc10cd69b8"
                }
            },
            {
                "id": "e25c0737-5753-4812-ab5c-94813e067ec9",
                "category": "FACEMAP",
                "allowedChannels": [
                    "WEB",
                    "SDK"
                ]
            },
            {
                "id": "bce8a24b-16ba-46a8-994e-fa76e4c4845b",
                "category": "SELFIE",
                "allowedChannels": [
                    "WEB",
                    "API",
                    "SDK"
                ],
                "api": {
                    "token": "eyJhbGciOiJIUzUxMiIsInppcCI6IkdaSVAifQ.H4sIAAAAAAAA_5XOMQ7CMAwF0LtkxpKdOk7MxsjKDRInYWkBiUogIe5O2huw_v_09T-uvU-rOzoSUYka0XNSd3DZ7FxHHqLPFksA7WkCRq1QcmrQEYkbE1lsG98xU4-k5IFMCnDzHcrECFWqEVoVLWngV2__cLu0PvTj_lyXfIP1vlzB8jz7rduHvHRGDAmIMQB7GSeFK0zGOan2ZiG57w9fvJLI7AAAAA.0NpDK192_6kMSYfxFuqHPFkhdsKQBqieRvSqt3XAGLWRe7Y8u0aJalMa8TLEY8eA0XEw4TqRapVLDraRHUz4kQ",
                    "parts": {
                        "face": "https://api.amer-1.jumio.ai/api/v1/accounts/572ac7b5-9f83-409d-ba8e-f0014e411c7e/workflow-executions/41f71912-1c6b-4e2f-b340-d6dc10cd69b8/credentials/bce8a24b-16ba-46a8-994e-fa76e4c4845b/parts/FACE"
                    },
                    "workflowExecution": "https://api.amer-1.jumio.ai/api/v1/accounts/572ac7b5-9f83-409d-ba8e-f0014e411c7e/workflow-executions/41f71912-1c6b-4e2f-b340-d6dc10cd69b8"
                }
            }
        ]
    }
}